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ABOUT THIS CHAPTER 


This chapter describes the Resource Manager, the part of the Toolbox through 
which an application accesses various resources that it uses, such as menus, 
fonts, and icons. It discusses resource files, where resources are stored. 
Resources form the foundation of every Macintosh application; even the 
application's code is a resource. In a resource file, the resources used by the 
application are stored separately from the code for flexibility and ease of 
maintenance. 


You can use an existing program for creating and editing resource files, or 
write one of your own; these programs will call Resource Manager routines. 
Usually you'll access resources indirectly through other parts of the Toolbox, 
such as the Menu Manager and the Font Manager, which in turn call the Resource 
Manager to do the low-level resource operations. In some cases, you may need to 
call a Resource Manager routine directly. 


Familiarity with Macintosh files, as described in the File Manager chapter, is 
useful if you want a complete understanding of the internal structure of a 
resource file; however, you don't need it to be able to use the Resource 
Manager. 


If you're going to write your own program to create and edit resource files, you 
also need to know the exact format of each type of resource. The chapter 
describing the part of the Toolbox that deals with a particular type of resource 
will tell you what you need to know for that resource. 


The speed and efficiency of the Resource Manager have been significantly 
enhanced in the 128K ROM. Nine routines have been added; seven are functional 
counterparts of 64K ROM routines but search only the current resource file, and 
two routines are new. Additional standard resource types have been defined, two 
new result codes have been added, and the reporting of error conditions has been 
improved. 


This chapter also describes changes to the Resource Manager, and the contents of 
the Macintosh SE and Macintosh II ROMs and of System file version 4.1. 
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ABOUT THE RESOURCE MANAGER 


Macintosh applications make use of many resources, such as menus, fonts, and 
icons, which are stored in resource files. For example, an icon resides ina 
resource file as a 32-by-32 bit image, and a font as a large bit image 
containing the characters of the font. In some cases the resource consists of 
descriptive information (such as, for a menu, the menu title, the text of each 
command in the menu, whether the command is checked with a check mark, and so 
on). The Resource Manager keeps track of resources in resource files and 
provides routines that allow applications and other parts of the Toolbox to 
access them. 


There's a resource file associated with each application, containing the 
resources specific to that application; these resources include the application 
code itself. There's also a system resource file, which contains standard 
resources shared by all applications (called system resources). 


The resources used by an application are created and changed separately from the 
application's code. This separation is the main advantage to having resource 
files. A change in the title of a menu, for example, won't require any 
recompilation of code, nor will translation to another language. 


The Resource Manager is initialized by the system when it starts up, and the 
system resource file is opened as part of the initialization. Your 

application's resource file is opened when the application starts up. When 
instructed to get a certain resource, the Resource Manager normally looks first 
in the application's resource file and then, if the search isn't successful, in 
the system resource file. This makes it easy to share resources among 
applications and also to override a system resource with one of your own (if you 
want to use something other than a standard icon in an alert box, for example). 


Resources are grouped logically by function into resource types. You refer to a 
resource by passing the Resource Manager a resource specification, which 
consists of the resource type and either an ID number or a name. Any resource 
type is valid, whether one of those recognized by the Toolbox as referring to 
standard Macintosh resources (such as menus and fonts), or a type created for 
use by your application. Given a resource specification, the Resource Manager 
will read the resource into memory and return a handle to it. 


Note: The Resource Manager knows nothing about the formats of the individual 
types of resources. Only the routines in the other parts of the Toolbox 
that call the Resource Manager have this knowledge. 


While most access to resources is read-only, certain applications may want to 
modify resources. You can change the content of a resource or its ID number, 
name, or other attributes—everything except its type. For example, you can 
designate whether the resource should be kept in memory or whether, as is normal 
for large resources, it can be removed from memory and read in again when 
needed. You can change existing resources, remove resources from the resource 
file altogether, or add new resources to the file. 
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Resource files aren't limited to applications; anything stored in a file can 
have its own resources. For instance, an unusual font used in only one document 
can be included in the resource file for that document rather than in the system 
resource file. 


Note: Although shared resources are usually stored in the system resource 
file, you can have other resource files that contain resources shared 
by two or more applications (or documents, or whatever). 


A number of resource files may be open at one time; the Resource Manager 
searches the files in the reverse of the order that they were opened. Since the 
system resource file is opened when the Resource Manager is initialized, it's 
always searched last. The search starts with the most recently opened resource 
file, but you can change it to start with a file that was opened earlier. (See 
Figure 1.) 


Order of Usual search You can change 

opening : path: it to this: ox this: 
Opened Document’s 

last resource file 


Opened Application’ 
Secor resource file 


Opened SVSteM LESOULCE 
first file 


Figure 1—-Resource File Sharing 


Figure 1—Resource File Searching 
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OVERVIEW OF RESOURCE FILES 


Resources may be put in a resource file with the aid of the Resource Editor, or 
with whatever tools are provided by the development system you're using. 


A resource file is not a file in the strictest sense. Although it's functionally 
like a file in many ways, it's actually just one of two parts, or forks, of a 
file (see Figure 2). Every file has a resource fork and a data fork (either of 
which may be empty). The resource fork of an application file contains not only 
the resources used by the application but also the application code itself. The 
code may be divided into different segments, each of which is a resource; this 
allows various parts of the program to be loaded and purged dynamically. 
Information is stored in the resource fork via the Resource Manager. The data 
fork of an application file can contain anything an application wants to store 
there. Information is stored in the data fork via the File Manager. 


The application’s Initially empty; 

resources (which the application 

include its code} may store data 
here 


Fesource fork Data fork 
C"resource file") 


Figure 2-—An Application File 
Figure 2—An Application File 


As shown in Figure 3, the system resource file has this same structure. The 
resource fork contains the system resources and the data fork contains "patches" 
to the routines in the Macintosh ROM. Figure 3 also shows the structure of a 
file containing a document; the resource fork contains the document's resources 
and the data fork contains the data that comprises the document. 


To open a resource file, the Resource Manager calls the appropriate File Manager 
routine and returns the reference number it gets from the File Manager. This is 
a number greater than 0 by which you can refer to the file when calling other 
Resource Manager routines. 
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Note: This reference number is actually the path reference number, as 
described in the File Manager chapter. 


Most of the Resource Manager routines don't require the resource file's 
reference number as a parameter. Rather, they assume that the current resource 
file is where they should perform their operation (or begin it, in the case of a 
search for a resource). The current resource file is the last one that was 
opened unless you specify otherwise. 


The document’s 
resources 


The system system code: 
resources patches to 
ROM routines 


Resource fork Data fork 
€"resource file") 


Resource fork Data fork 
("resource file") 
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system Resource File Document File 


Figure 3—Other Files 
Figure 3—Other Files 


A resource file consists primarily of resource data and a resource map. The 
resource data consists of the resources themselves (for example, the bit image 
for an icon or the title and commands for a menu). The resource map contains an 
entry for each resource that provides the location of its resource data. Each 
entry in the map either gives the offset of the resource data in the file or 
contains a handle to the data if it's in memory. The resource map is like the 
index of a book; the Resource Manager looks in it for the resource you specify 
and determines where its resource data is located. 


The resource map is read into memory when the file is opened and remains there 
until the file is closed. Although for simplicity we say that the Resource 
Manager searches resource files, it actually searches the resource maps that 
were read into memory, and not the resource files on the disk. 


Resource data is normally read into memory when needed, though you can specify 
that it be read in as soon as the resource file is opened. When read in, 
resource data is stored in a relocatable block in the heap. Resources are 
designated in the resource map as being either purgeable or unpurgeable; if 
purgeable, they may be removed from the heap when space is required by the 
Memory Manager. Resources consisting of a relatively large amount of data are 
usually designated as purgeable. Before accessing such a resource through its 
handle, you ask the Resource Manager to read the resource into memory again if 
it has been purged. 
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Note: Programmers concerned about the amount of available memory should be 
aware that there's a 12-byte overhead in the resource map for every 
resource and an additional 12-byte overhead for memory management if 
the resource is read into memory. 


To modify a resource, you change the resource data or resource map in memory. 
The change becomes permanent only at your explicit request, and then only when 
the application terminates or when you call a routine specifically for updating 
or closing the resource file. 


Each resource file also may contain up to 128 bytes of any data the application 
wants to store there. 
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RESOURCE SPECIFICATION 


In a resource file, every resource is assigned a type, an ID number, and 
optionally a name. When calling a Resource Manager routine to access a resource, 
you specify the resource by passing its type and either its ID number or its 
name. This section gives some general information about resource specification. 


Resource Types 


The resource type is a sequence of any four characters (printing or 
nonprinting). Its Pascal data type is: 


TYPE ResType = PACKED ARRAY[1..4] OF CHAR; 


The following standard resource types have been defined (System file 4.1 or 
later). All-uppercase resource types are listed first. 


Resource Meaning 


type 

‘ALRT' Alert template 

'ADBS' Apple Desktop Bus service routine 
"BNDL' Bundle 

'CACH' RAM cache code 

'CDEF ' Control definition function 

‘CNTL' Control template 

‘CODE’ Application code segment 

‘CURS' Cursor 

'DITL' Item list in a dialog or alert 
‘DLOG' Dialog template 

'DRVR' Desk accessory or other device driver 
'DSAT' System startup alert table 

"FKEY ' Command-Shift-number routine 

'FMTR' 3 1/2-inch disk formatting code 
‘FOND ' Font family record 

‘FONT ' Font 

'FREF' File reference 

'FRSV' IDs of fonts reserved for system use 
‘FWID' Font widths 

‘ICN#' Icon list 

‘ICON ' Icon 

‘INIT' Initialization resource 

‘INTL' International resource 

‘INT#' List of integers owned by Find File 
"KCAP' Physical layout of keyboard (used by Key Caps desk accessory) 
"KCHR' ASCII mapping (software) 

"KMAP ' Keyboard mapping (hardware) 

'KSWP ' Keyboard script table 

'LDEF' List definition procedure 
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Menu bar 

Default menu definition procedure 
Menu definition procedure 

Menu 

Mouse tracking code 

Appletalk bundle 

128K ROM font 

Package 

Pattern (The space is required. ) 
Pattern list 

Printing code 

Picture 

Print record 

Device type for Chooser 

Device type for Chooser 

ROM patch code 

Device type for Chooser 

Code for overriding ROM resources 
List of ROM resources to override 
RAM Serial Driver 

Script symbol 

String (The space is required. ) 
String list 

Window definition function 

Window template 

Alert color table 

Internal AppleTalk resource 

Bit maps used by the Control Panel 
Copy of boot blocks 

Control color table 

Color Macintosh icon 

Cached icon lists used by Chooser and Control Panel 
Color look-up table 

Color cursor 

Used by the Control Panel 

Dialog color table 

Font color table 

Font information 

Color correction table 

Color table dialog item 

Installer script 

Date and time formats 

Names of days and months 
International Utilities Package sort hooks 
International Utilities Package script bundles 
International configuration for Script Manager 
Low memory globals 

Mouse tracking 

Menu color information table 
Internal memory requirements for MakeITable 
AppleTalk configuration code 
Rectangle positions 

Color palette 

Pixel pattern 

Sound (The space is required. ) 
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'snth' Synthesizer 
‘wctb' Window color table 


Uppercase and lowercase letters are distinguished in resource types. You can use 
any four-character sequence, except those listed above, and those sequences 
consisting entirely of lowercase letters (reserved by Apple), for resource types 
specific to your application. There's no need to register your resource types 
with Apple since they'll only be used by your application. 


Resource ID Numbers 


Every resource has an ID number, or resource ID. The resource ID should be 
unique within each resource type, but resources of different types may have the 
same ID. If you assign the same resource ID to two resources of the same type, 
the second assignment of the ID will override the first, thereby making the 
first resource inaccessible by ID. 


Warning: Certain resources contain the resource IDs of other resources; for 
instance, a dialog template contains the resource ID of its item 
list. In order not to duplicate an existing resource ID, a program 
that copies resources may need to change the resource ID of a 
resource; such a program may not, however, change the ID where it 
is referred to by other resources. For instance, an item list's 
resource ID contained in a dialog template may not be changed, 
even though the actual resource ID of the item list was changed to 
avoid duplication; this would make it impossible for the template 
to access the item list. Be sure to verify, and if necessary correct, 
the IDs contained within such resources. (For related information, 
see the section "Resource IDs of Owned Resources" below. ) 


By convention, the ID numbers are divided into the following ranges: 


Range Description 
—32768 through —16385 Reserved; do not use 
—16384 through -1 Used for system resources owned by other system 
resources (explained below) 
0 through 127 Used for other system resources 
128 through 32767 Available for your use in whatever way you wish 


Note: The chapters that describe the different types of resources in detail 
give information about resource types that may be more restrictive 
about the allowable range for their resource IDs. A device driver, 
for instance, can't have a resource ID greater than 31. 


Resource IDs of Owned Resources 


This section is intended for advanced programmers who are writing their own desk 
accessories (or other drivers), or special types of windows, controls, and 
menus. It's also useful in understanding the way that resource-copying programs 
recognize resources that are associated with each other. 


@ SpInside Macintosh * Version 1.0 * November 1989 * Apple Computer 
THE RESOURCE MANAGER ¢« 11 of 54 


Certain types of system resources may have resources of their own in the system 
resource file; the "owning" resource consists of code that reads the "owned" 
resource into memory. For example, a desk accessory might have its own pattern 
and string resources. A special numbering convention is used to associate owned 
system resources with the resources they belong to. This enables resource- 
copying programs to recognize which additional resources need to be copied along 
with an owning resource. An owned system resource has the ID illustrated in 
Figure 4. 


15 14 13 11 10 ao 4 a 


Figure 4-—Resource ID of an Owned System Resouce 


Figure 4—Resource ID of an Owned System Resource 


Bits 14 and 15 are always 1. Bits 11-13 specify the type of the owning resource, 
as follows: 


Type bits Type 


000 "DRVR' 
001 "WDEF ' 
010 'MDEF' 
011 'CDEF' 
100 "PDEF' 
101 "PACK' 
110 Reserved for future use 
111 Reserved for future use 


Bits 5-10 contain the resource ID of the owning resource (limited to 0 through 
63). Bits 0-4 contain any desired value (0 through 31). 


Certain types of resources can't be owned, because their IDs don't conform to 
the special numbering convention described above. For instance, while a resource 
of type 'WDEF' can own other resources, it cannot itself be owned since its 
resource ID can't be more than 12 bits long (as described in the Window Manager 
chapter). Fonts are also an exception because their IDs include the font size. 
The chapters describing the different types of resources provide detailed 
information about such restrictions. 


An owned resource may itself contain the ID of a resource associated with it. 
For instance, a dialog template owned by a desk accessory contains the resource 
ID of its item list. Though the item list is associated with the dialog 
template, it's actually owned (indirectly) by the desk accessory. The resource 
ID of the item list should conform to the same special convention as the ID of 
the template. For example, if the resource ID of the desk accessory is 17, the 
IDs of both the template and the item list should contain the value 17 in bits 
5-10. 


eeeClick on the X-Ref button, and refer to Technical Note #6.¢ee 
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As mentioned above, a program that copies resources may need to change the 
resource ID of a resource in order not to duplicate an existing resource ID. 
Bits 5-10 of resources owned, directly or indirectly, by the copied resource 
will also be changed when those resources are copied. For instance, in the above 
example, if the desk accessory must be given a new ID, bits 5-10 of both the 
template and the item list will also be changed. 


Warning: Remember that while the ID of an owned resource may be changed by a 
resource-copying program, the ID may not be changed where it appears 
in other resources (such as an item list's ID contained in a dialog 
template). 


Resource Names 


A resource may optionally have a resource name. Like the resource ID, the 
resource name should be unique within each type; if you assign the same resource 
name to two resources of the same type, the second assignment of the name will 
override the first, thereby making the first resource inaccessible by name. When 
comparing resource names, the Resource Manager ignores case (but does not ignore 
diacritical marks). 


Resource References 


The entries in the resource map that identify and locate the resources in a 
resource file are known as resource references. Using the analogy of an index of 
a book, resource references are like the individual entries in the index 

(see Figure 5). 


Every resource reference includes the type, ID number, and optional name of the 
resource. Suppose you're accessing a resource for the first time. You pass a 
resource specification to the Resource Manager, which looks for a match among 
all the references in the resource map of the current resource file. If none is 
found, it looks at the references in the resource map of the next resource file 
to be searched. (Remember, it looks in the resource map in memory, not in the 
file.) Eventually it finds a reference matching the specification, which tells 
it where the resource data is in the file. After reading the resource data into 
memory, the Resource Manager stores a handle to that data in the reference 
(again, in the resource map in memory) and returns the handle so you can use it 
to refer to the resource in subsequent routine calls. 
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Figure 5—Resource References in Resource Maps 


Figure 5—Resource References in Resource Maps 


Every resource reference also contains certain resource attributes that 
determine how the resource should be dealt with. In the routine calls for 
setting or reading them, each attribute is specified by a bit in the low-order 
byte of a word, as illustrated in Figure 6. 


low-order byte = Chigh-ovder byte is ienoveds 
7 6 5 4 3 2 1 +0 


a a a 


| 1 if to be Written to resource file, 0 if not 
1 if to be preloaded, O if not 
1 if protected, 0 if not 
1 if locked, 0 if not 


1 if purgeable, 0 if not 
1 if read into syetem heap, 0 if application heap 


* reserved for use by the Resource Manager 


Figure 6—-Resource Attributes 


Figure 6—Resource Attributes 


The Resource Manager provides a predefined constant for each attribute, in which 
the bit corresponding to that attribute is set. 
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CONST resSysHeap 64; {set if read into system heap} 


resPurgeable = 32; {set if purgeable} 

resLocked = 16; {set if locked} 

resProtected = 8; {set if protected} 

resPreload = 4; {set if to be preloaded} 

resChanged S25 {set if to be written to resource file} 


Warning: Your application should not change the setting of bit 0 or 7, nor 
should it set the resChanged attribute directly. (ResChanged is set 
as a side effect of the procedure you call to tell the Resource 
Manager that you've changed a resource. ) 


The resSysHeap attribute should not be set for your application's resources. If 
a resource with this attribute set is too large for the system heap, the bit 
will be cleared, and the resource will be read into the application heap. 


Since a locked resource is neither relocatable nor purgeable, the resLocked 
attribute overrides the resPurgeable attribute; when resLocked is set, the 
resource will not be purgeable regardless of whether resPurgeable is set. 


If the resProtected attribute is set, the application can't use Resource Manager 
routines to change the ID number or name of the resource, modify its contents, 
or remove the resource from the resource file. The routine that sets the 
resource attributes may be called, however, to remove the protection or just 
change some of the other attributes. 


The resPreload attribute tells the Resource Manager to read this resource into 
memory immediately after opening the resource file. This is useful, for example, 
if you immediately want to draw ten icons stored in the file; rather than read 
and draw each one individually in turn, you can have all of them read in when 
the file is opened and just draw all ten. 


The resChanged attribute is used only while the resource map is in memory; it 
must be 0 in the resource file. It tells the Resource Manager whether this 
resource has been changed. 
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RESOURCES IN ROM 


The information presented in this section is useful only to assembly- language 
programmers. 


With the 64K ROM, many of the system resources are stored in the system resource 
file. With the 128K ROM, the following system resources are stored in ROM: 


Type ID Description 


"CURS ' 1 IBeamCursor 

"CURS ' 2 CrossCursor 

'CURS' 3 PlusCursor 

'CURS' 4 WatchCursor 

"DRVR' 2 Printer Driver shell (.Print) 
'DRVR' 3 Sound Driver (.Sound) 

'DRVR' 4 Disk Driver (.Sony) 

‘DRVR' 9 AppleTalk driver (.MPP) 

"DRVR' A AppleTalk driver (.ATP) 

‘FONT ' 0 Name of system font 

‘FONT ' C System font 

'MDEF ' 0 Default menu definition procedure 
"PACK' 4 Floating-Point Arithmetic Package 
"PACK' 5 Transcendental Functions Package 
"PACK' 7 Binary-Decimal Conversion Package 
‘SERD ' 0 Serial Driver 

'WDEF' 0 Default window definition function 


Note: The Sound Driver, Disk Driver, and Serial Driver are in the 64K ROM, 
but are not stored as resources. 


Certain system resources were placed in the 128K ROM for quick access. The 
Macintosh SE and Macintosh II ROMs include additional resources in ROM; they're 
outlined below. 


The following system resources are stored in the Macintosh SE ROM (the resource 
IDs are in hexadecimal): 


Type ID Description 


'CDEF' 0 Default button definition procedure 
'CDEF' 1 Default scroll bar definition procedure 
'CURS' 1 IBeamCursor 

'CURS' 2 CrossCursor 

'CURS ' 3 PlusCursor 

"CURS' 4 WatchCursor 

'DRVR' 3 Sound Driver (.Sound) 

'DRVR' 4 Disk Driver (.Sony) 

'DRVR' 9 AppleTalk driver (.MPP) 

"DRVR' A AppleTalk driver (.ATP) 

"DRVR' 28 AppleTalk driver (.XPP) 
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‘FONT’ 
‘FONT’ 
‘FONT’ 
‘FONT’ 
‘FONT’ 
"KMAP ' 
"MBDF ' 
‘MDEF ' 
‘PACK’ 
‘PACK’ 
‘PACK’ 
'SERD' 
‘WDEF ' 
‘WDEF ' 


The following system resources are stored in the Macintosh II ROM (the resource 


N 
oO 
(to) 


FOONUBOOO® 


Name of system font 

System font (Chicago 12) 

Geneva 9 font 

Geneva 12 font 

Monaco 9 font 

Keyboard map for keyboard driver 

Default menu bar procedure 

Default menu definition procedure 

Floating-Point Arithmetic Package 

Transcendental Functions Package 

Binary-Decimal Conversion Package 

Serial Driver 

Default window definition function (document window) 
Default window definition function (rounded window) 


IDs are in hexadecimal): 


Type 


'CDEF' 
'CDEF' 
‘CURS ' 
‘CURS ' 
‘CURS ' 
‘CURS ' 
"DRVR' 
"DRVR' 
"DRVR' 
"DRVR' 
"DRVR' 
'FONT' 
'FONT' 
'FONT' 
‘FONT' 
'FONT' 
‘FONT' 
'FONT' 
"KCHR' 
"KMAP ' 
'MBDF ' 
'MDEF' 
"NFNT' 
"NFNT' 
"NFNT' 
"PACK' 
"PACK' 
"PACK' 
"SERD ' 
'WDEF ' 
'WDEF ' 
‘cctb' 
‘clut' 
‘clut' 
‘clut' 


ID 


AONPFOBRWRWNFEO 


N 


BNFORPOONUBNWNOO 


@ SpInside Macintosh * Version 1.0 * November 1989 * Apple Computer 
THE RESOURCE MANAGER ¢e 17 of 54 


Description 


Default button definition procedure 
Default scroll bar definition procedure 
IBeamCursor 

CrossCursor 

PlusCursor 

WatchCursor 

Sound Driver (.Sound) 

Disk Driver (.Sony) 

AppleTalk driver (.MPP) 

AppleTalk driver (.ATP) 

AppleTalk driver (.XPP) 

Name of system font 

System font (Chicago 12) 

Name of Geneva font 

Geneva 9 font 

Geneva 12 font 

Name of Monaco font 

Monaco 9 font 

ASCII mapping (software) 

Keyboard mapping (hardware) 

Default menu bar procedure 

Default menu definition procedure 
Chicago 12 font (4-bit) 

Chicago 12 font (8-bit) 

Geneva 9 font (4-bit) 
Floating-Point Arithmetic Package 
Transcendental Functions Package 
Binary-Decimal Conversion Package 
Serial Driver 

Default window definition function (document window) 
Default window definition function (rounded window) 
Control color table 

Color look-up table 

Color look-up table 

Color look-up table 


‘clut' 8 Color look-up table 

‘clut' 7F Color look-up table 

'gama' 0 Color correction table 

'mitq' 0 Internal memory requirements for MakeITable 
‘snd ' 1 Brass horn 

‘wctb' 0 Window color table 


When the Macintosh is turned on, a call is made to the InitResources function. 
The Resource Manager creates a special heap zone within the system heap, and 
builds a resource map that points to the ROM resources. 


In order to use the ROM resources in your calls to the Resource Manager, the ROM 
map must be inserted in front of the map for the system resource file prior to 
making the call. The global variable RomMapInsert is used for this purpose; it 
tells the Resource Manager to insert the ROM map for the next call only. An 
adjacent global variable, TmpResLoad, is also useful; when RomMapInsert is TRUE, 
TmpResLoad determines whether the value of the global variable ResLoad is taken 
to be TRUE or FALSE (overriding the actual value of ResLoad) for the next call 
only. Figure 7 shows these two variables. 


RomMaplasert (oye) TmpResLoad (ivte} 


Figure 7-RomMapinsert and TmpResLoad 
Figure 7—RomMapInsert and TmpResLoad 


Two global constants, each a word in length, are provided for setting these 
variables in tandem: mapTrue inserts the ROM map with SetResLoad(TRUE) and 
mapFalse inserts the ROM map with SetResLoad(FALSE). As noted, both RomMapInsert 
and TmpResLoad are cleared after each Resource Manager call. 


Note: There is no real resource file associated with the ROM resources; the 
ROM map has a path reference number of 1 (an illegal path reference 
number). There are two ways to determine if a handle references a ROM 
resource. First, you can set up TmpResLoad and RomMapInsert and call 
HomeResFile; if 1 is returned, the handle is to a ROM resource. Second, 
you can dereference the handle and see if the master pointer points 
into the ROM space by comparing it to the global variable ROMBase. 


To use the ROM resources in your calls to the Resource Manager, the ROM map must 
be inserted in front of the map for the System Resource File prior to making the 
call. Unless the ROM map is inserted, the GetResource call will not search the 
ROM resources. Sometimes, however, you'll first want to try to get the resource 
from any open resource files, and then if it's not found, to get it from ROM. A 
new routine, RGetResource, lets you do this easily. It searches the chain of 
open resource files (including the System Resource File) for the given resource; 
if it's not there, it looks in ROM. 


Overriding ROM Resources 


This section explains how to override ROM resources. 
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Warning: As with intercepting system traps using the SetTrapAddress procedure, 
you should override ROM resources only if it's absolutely necessary 
and you understand the situation completely. 


You can override some of the ROM resources, such as 'CURS' resources, simply by 
putting the substitute resource in your application's resource fork. Other ROM 
resources however, such 'DRVR' and 'PACK' resources, cannot be overridden in 
this way because they are already referenced and in use when your application is 
launched. 


Whenever InitResource is called, the ROM map is rebuilt. (Do not use 
InitResources to rebuild the ROM map.) Each time the ROM map is rebuilt, the 
Resource Manager looks in the system resource file for a 'ROvr' resource 0. If 
it finds such a resource, it loads it into memory and jumps to this resource via 
a JSR instruction. The code in the 'ROvr' resource looks in the system resource 
file for all resources of type 'ROv#' whose version word matches the version 
word of the ROM (see Figure 8). For example, to override a resource in the 128K 
ROM, the version must be $75. 


version number of ROM Cwords 


number of resources - 1 (word) 


resource trpe (4 bortes4 
resource ID (word) 


resource type (4 botes4 
resource ID (word) 


Figure 6-Struocture of an "ROv#' Resouce 
Figure 8—-Structure of an 'ROv#' Resource 


To override ROM resources in this way, you'll first need a copy of an 'ROvr' 
resource; you can obtain one by writing to: 


Developer Technical Support 
Apple Computer, Inc. 

20525 Mariani Avenue, M/S 75-3T 
Cupertino, CA 95014 


You'll then need to create an 'ROv#' resource listing the resources you want to 
override. 
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RESOURCES IN THE SYSTEM FILE 


The System Resource File contains standard resources that are shared by all 
applications, and are used by the Macintosh Toolbox and Operating System as 
well. This file can be modified by the user with the Installer and Font/DA Mover 
programs. 


Warning: Your program should not directly add resources to, or delete 
resources from, the System Resource File. 


Applications should not alter resources in the System file, except for resources 
owned by the application, as discussed in the Resource Manager. 

With applications that need to install drivers, fonts, or desk accessories, 
developers should ship an Apple-released copy of the file along with either the 
Installer and a script (for drivers) or the Font/DA Mover (for fonts and desk 
accessories). 


Note: Some of the resources in the System Resource File are also contained 
in the 128K and 256K ROMs; they're duplicated in the System Resource 
File for compatibility with machines in which these resources are not 
in ROM. 


The rest of this section presents an overview of the System Resource File's 
resources, grouped by function. 


Packages 


The System Resource File contains the standard Macintosh packages and the 
resources they use (or own): 


e the List Manager Package ('PACK' resource 0), and the standard list 
definition procedure ('LDEF' resource 0) 

e the Disk Initialization Package ('PACK' resource 2), and code (resource 
type 'FMTR') used in formatting disks 

« the Standard File Package ('PACK' resource 3), and resources used to 

create its alerts and dialogs (resource types 'ALRT', 'DITL', and 'DLOG') 

the Floating-Point Arithmetic Package ('PACK' resource 4) 

the Transcendental Functions Package ('PACK' resource 5) 

the International Utilities Package ('PACK' resource 6) 

the Binary-Decimal Conversion Package ('PACK' resource 7) 

the Color Picker Package ('PACK' resource 12) 


eoeeee 


Drivers and Desk Accessories 


Certain device drivers (including desk accessories) and the resources they use 
or own are found in the System Resource File; these resources include 
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the .PRINT driver ('DRVR' resource 2) that communicates between the Print 
Manager and the printer. 

the .MPP, .ATP, and .XPP drivers ('DRVR' resources 9, 10, and 28 
respectively) used by version 42 of AppleTalk. 

the Control Panel desk accessory ('DRVR' resource 18) and the resources 
used in displaying its various options. The Control Panel also uses a 
resource of type 'clst' to list the cached icons of the devices in order 
to improve performance. 

the Chooser desk accessory, which uses the same class of resources as the 
Control Panel, including its own '‘clst'. 


Patches 


For each ROM (64K, 128K, 256K) there are two patch resources of type 'PTCH' that 
provide updates for ROM routines. At startup, the machine's ROM is checked and 
the appropriate 'PTCH' resources are installed and locked in the system heap. 


The 'PTCH' resources are: 
ALL ROMS 'PTCH' 0 
64K ROM 'PTCH' 105 
128K ROM 'PTCH' 117 
256K ROM (Macintosh SE) 'PTCH' 630 
256K ROM (Macintosh ITI) 'PTCH' 376 


General Resources 


Other resources contained in the System Resource File include 


e 


Standard definition procedures for creating windows, menus, controls, 
and lists. 

System fonts and font families (resource types 'FONT' and 'FOND'). 
System icons. 

The screen utility resources 'FKEY' 3 and 4, which execute a MacPaint 
screen snapshot when Command-Shift-3 is pressed, and print a screen 
snapshot when Command-Shift-4 is pressed, respectively. Note that 
Command-Shift-4 only works with the ImageWriter®; it is useful for a 
quick print, but should not be an application's print strategy. 

Mouse tracking resources: 'mcky' 0 to 4, which provide parameters for 
various mouse tracking setups; 'MMAP' 0, which provides mouse tracking 
code for use when it is not in ROM. 

Key mapping resources, which implement keyboard mapping in conjunction 
with the Apple Desktop Bus: 'ADBS' 2, 'KMAP' 1 and 2, and 'KCHR', which 
has IDs for each language. Note that 'INIT' resources 1 and 2, which 
used to handle key translation, now point to the 'ADBS'/'KCHR' system 
instead. 

Color resources: ‘wctb' 0, 'cctb' 0, and 'mitq' 0, which implement color 
tables, and 'cicn' 0, the color Macintosh icon. See the Color Quickdraw 
and Color Manager chapters for more information. 


Notice that some of the resources listed above are "templates". A template is a 
list of parameters used to build a Toolbox object; it is not the object itself. 
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For example, a window template contains information specifying the size and 
location of the window, its title, whether it's visible, and so on. After the 
Window Manager has used this information to build the window in memory, the 
template isn't needed again until the next window using that template is 


created. 


eeeClick on the X-Ref button, and refer to Technical Note #32.¢¢¢ 


You can use any four-character sequence (except those listed above) for resource 


types specific to your application. 
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USING THE RESOURCE MANAGER 


The Resource Manager is initialized automatically when the system starts up: 
The system resource file is opened and its resource map is read into memory. 
Your application's resource file is opened when the application starts up; you 
can call CurResFile to get its reference number. You can also call OpenResFile 
to open any resource file that you specify by name, and CloseResFile to close 
any resource file. A function named ResError lets you check for errors that may 
occur during execution of Resource Manager routines. 


Note: These are the only routines you need to know about to use the Resource 
Manager indirectly through other parts of the Toolbox. 


Normally when you want to access a resource for the first time, you'll specify 
it by type and ID number (or type and name) in a call to GetResource (or 
GetNamedResource). In special situations, you may want to get every resource of 
each type. There are two routines which, used together, will tell you all the 
resource types that are in all open resource files: CountTypes and GetIndType. 
Similarly, CountResources and GetIndResource may be used to get all resources of 
a particular type. 


If you don't specify otherwise, GetResource, GetNamedResource, and 
GetIndResource read the resource data into memory and return a handle to it. 
Sometimes, however, you may not need the data to be in memory. You can use a 
procedure named SetResLoad to tell the Resource Manager not to read the resource 
data into memory when you get a resource; in this case, the handle returned for 
the resource will be an empty handle (a pointer to a NIL master pointer). You 
can pass the empty handle to routines that operate only on the resource map 
(such as the routine that sets resource attributes), since the handle is enough 
for the Resource Manager to tell what resource you're referring to. Should you 
later want to access the resource data, you can read it into memory with the 
LoadResource procedure. Before calling any of the above routines that read the 
resource data into memory, it's a good idea to call SizeResource to see how much 
Space is needed. 


Normally the Resource Manager starts looking for a resource in the most recently 
opened resource file, and searches other open resource files in the reverse of 
the order that they were opened. In some situations, you may want to change 
which file is searched first. You can do this with the UseResFile procedure. One 
such situation might be when you want a resource to be read from the same file 
as another resource; in this case, you can find out which resource file the 
other resource was read from by calling the HomeResFile function. 


Once you have a handle to a resource, you can call GetResInfo or GetResAttrs to 
get the information that's stored for that resource in the resource map, or you 
can access the resource data through the handle. (If the resource was designated 
as purgeable, first call LoadResource to ensure that the data is in memory.) 


Usually you'll just read resources from previously created resource files with 
the routines described above. You may, however, want to modify existing 
resources or even create your own resource file. To create your own resource 
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file, call CreateResFile (followed by OpenResFile to open it). The AddResource 
procedure lets you add resources to a resource file; to be sure a new resource 
won't override an existing one, you can call the UniqueID function to get an ID 
number for it. To make a copy of an existing resource, call DetachResource 
followed by AddResource (with a new resource ID). There are a number of 
procedures for modifying existing resources: 


« To remove a resource, call RmveResource. 

« If you've changed the resource data for a resource and want the changed 
data to be written to the resource file, call ChangedResource; it signals 
the Resource Manager to write the data out when the resource file is later 
updated. 

« To change the information stored for a resource in the resource map, call 
SetResInfo or SetResAttrs. If you want the change to be written to the 
resource file, call ChangedResource. (Remember that ChangedResource will 
also cause the resource data itself to be written out.) 


These procedures for adding and modifying resources change only the resource map 
in memory. The changes are written to the resource file when the application 
terminates (at which time all resource files other than the system resource file 
are updated and closed) or when one of the following routines is called: 


e CloseResFile, which updates the resource file before closing it 

¢ UpdateResFile, which simply updates the resource file 

e WriteResource, which writes the resource data for a specified resource 
to the resource file 
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RESOURCE MANAGER ROUTINES 


Assembly-language note: Except for LoadResource, all Resource Manager routines 
preserve all registers except AQ and DQ. LoadResource 
preserves AO and DO as well. 


Initialization 


Although you don't call these initialization routines (because they're executed 
automatically for you), it's a good idea to familiarize yourself with what they 
do. 


FUNCTION InitResources : INTEGER; 


InitResources is called by the system when it starts up, and should not be 
called by the application. It initializes the Resource Manager, opens the system 
resource file, reads the resource map from the file into memory, and returns a 
reference number for the file. 


Assembly-language note: The name of the system resource file is stored in 
the global variable SysResName; the reference number 
for the file is stored in the global variable SysMap. 
A handle to the resource map of the system resource 
file is stored in the variable SysMapHndl. 


Note: The application doesn't need the reference number for the system 
resource file, because every Resource Manager routine that has a 
reference number as a parameter interprets 0 to mean the system 
resource file. 


PROCEDURE RsrcZoneInit; 


RsrcZoneInit is called automatically when your application starts up, to 
initialize the resource map read from the system resource file; normally you'll 
have no need to call it directly. It "cleans up" after any resource access that 
may have been done by a previous application. First it closes all open resource 
files except the system resource file. Then, for every system resource that was 
read into the application heap (that is, whose resSysHeap attribute is 0), it 
replaces the handle to that resource in the resource map with NIL. This lets the 
Resource Manager know that the resource will have to be read in again 

(since the previous application heap is no longer around). 


Opening and Closing Resource Files 


When calling the CreateResFile or OpenResFile routine, described below, you 
specify a resource file by its file name; the routine assumes that the file has 
a version number of 0 and is on the default volume. (Version numbers and volumes 
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are described in the File Manager chapter.) If you want the routine to apply to 
a file on another volume, just set the default volume to that volume. 


eeeClick on the X-Ref button, and refer to Technical Notes #101 & #214.¢+¢« 
PROCEDURE CreateResFile (fileName: Str255); 


CreateResFile creates a resource file containing no resource data. If there's no 
file at all with the given name, it also creates an empty data fork for the 
file. If there's already a resource file with the given name (that is, a 
resource fork that isn't empty), CreateResFile will do nothing and the ResError 
function will return an appropriate Operating System result code. 


Note: Before you can work with the resource file, you need to open it with 
OpenResFile. 


FUNCTION OpenResFile (fileName: Str255) : INTEGER; 


OpenResFile opens the resource file having the given name and makes it the 
current resource file. It reads the resource map from the file into memory and 
returns a reference number for the file. It also reads in every resource whose 
resPreload attribute is set. If the resource file is already open, it doesn't 
make it the current resource file; it simply returns the reference number. 


Note: You don't have to call OpenResFile to open the system resource file 
or the application's resource file, because they're opened when the 
system and the application start up, respectively. To get the reference 
number of the application's resource file, you can call CurResFile after 
the application starts up (before you open any other resource file). 


If the file can't be opened, OpenResFile will return —1 and the ResError 
function will return an appropriate Operating System result code. For example, 
an error occurs if there's no resource file with the given name. 


eeeClick on the X-Ref button, and refer to Technical Notes #74 & #232.¢e¢« 


Note: To open a resource file simply for block-level operations such as 
copying files (without reading the resource map into memory), you 
can call the File Manager function OpenRF. 


Assembly-language note: A handle to the resource map of the most recently 
opened resource file is stored in the global variable 
TopMapHndl. 


PROCEDURE CloseResFile (refNum: INTEGER); 
Given the reference number of a resource file, CloseResFile does the following: 


¢ updates the resource file by calling the UpdateResFile procedure 

¢ for each resource in the resource file, releases the memory it occupies 
by calling the ReleaseResource procedure 

« releases the memory occupied by the resource map 

« closes the resource file 
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If there's no resource file open with the given reference number, CloseResFile 
will do nothing and the ResError function will return the result code 
resFNotFound. A refNum of 0 represents the system resource file, but if you ask 
to close this file, CloseResFile first closes all other open resource files. 


A CloseResFile of every open resource file (except the system resource file) is 
done automatically when the application terminates. So you only need to call 
CloseResFile if you want to close a resource file before the application 
terminates. 


Checking for Errors 
FUNCTION ResError : INTEGER; 


Called after one of the various Resource Manager routines that may result in an 
error condition, ResError returns a result code identifying the error, if any. 
If no error occurred, it returns the result code 


CONST noErr = Q; {no error} 


If an error occurred at the Operating System level, it returns an Operating 
System result code, such as the File Manager "disk I/O" error or the Memory 
Manager “out of memory" error. (See Appendix A for a list of all result codes.) 
If an error happened at the Resource Manager level, ResError returns one of the 
following result codes: 


CONST resNotFound = -192; {resource not found} 
resFNotFound = -193; {resource file not found} 
addResFailed = -194; {AddResource failed} 
rmvResFailed = -196; {RmveResource failed} 


Each routine description tells which errors may occur for that routine. You can 
also check for an error after system startup, which calls InitResources, and 
application startup, which opens the application's resource file. 


Warning: In certain cases, the ResError function will return noError even 
though a Resource Manager routine was unable to perform the requested 
Operation; the routine descriptions give details about the 
circumstances under which this will happen. 


Assembly-language note: The current value of ResError is stored in the global 
variable ResErr. In addition, you can specify a 
procedure to be called whenever there's an error by 
storing the address of the procedure in the global 
variable ResErrProc (which is normally 0). Before 
returning a result code other than noErr, the ResError 
function places that result code in register DO and 
calls your procedure. 


eeeClick on the X-Ref button, and refer to Technical Note #78.+¢e« 
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In the 64K ROM, some error conditions resulting from certain Resource Manager 
routines are not reported by the ResError function. Two additional result codes 
are defined in the 128K ROM version of the Resource Manager: 


CONST resAttrErr 
mapReadErr 


198; {attribute does not permit operation} 
199; {map does not permit operation} 


In the 128K ROM, the following error conditions are reported by ResError: 


« The OpenResFile function checks to see that the information in the 
resource map is internally consistent; if it isn't, ResError returns 
mapReadError. 

« The CloseResFile procedure calls UpdateResFile. If UpdateResFile returns 
a nonzero result code, that result code will be returned by CloseResFile. 

e If you provide an index to GetIndResource (or GetlIndResource) that's 
either 0 or negative, the ResError function will return the result code 
resNotFound. 

e If you call DetachResource to detach a resource whose resChanged attribute 
has been set, ResError will return the result code resAttrErr. 

¢ If you call SetResInfo but the resProtected attribute is set, ResError 
will return the result code resAttrErr. 

e If you call ChangedResource but the resProtected attribute for the 
modified resource is set, the ResError function will return the result 
code resAttrErr. 

« If you call UpdateResFile but the mapReadOnly attribute for the resource 
file is set (described in the "Advanced Routines" section of the Resource 
Manager chapter), ResError will return the result code mapReadErr. 


Warning: If you call the GetResource and GetiResource functions with a 
resource type that isn't in any open resource file, they return NIL 
but the ResError function will return the result code noErr. With 
these calls, you must check that the handle returned is 

nonzero. 


Setting the Current Resource File 


When calling the CurResFile and HomeResFile routines, described below, be aware 
that for the system resource file the actual reference number is returned. You 
needn't worry about this number being used (instead of 0) in the routines that 
require a reference number; those routines recognize both 0 and the actual 
reference number as referring to the system resource file. 


FUNCTION CurResFile : INTEGER; 

CurResFile returns the reference number of the current resource file. You can 
call it when the application starts up to get the reference number of its 
resource file. 


Assembly-language note: The reference number of the current resource file is 
stored in the global variable CurMap. 


FUNCTION HomeResFile (theResource: Handle) : INTEGER; 
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Given a handle to a resource, HomeResFile returns the reference number of the 
resource file containing that resource. If the given handle isn't a handle to a 
resource, HomeResFile will return —1 and the ResError function will return the 
result code resNotFound. 


PROCEDURE UseResFile (refNum: INTEGER); 


Given the reference number of a resource file, UseResFile sets the current 
resource file to that file. If there's no resource file open with the given 
reference number, UseResFile will do nothing and the ResError function will 
return the result code resFNotFound. A refNum of 0 represents the system 
resource file. 


Open resource files are arranged as a linked list; the most recently opened file 
is at the end of the list and is the first one the Resource Manager searches 
when looking for a resource. UseResFile lets you start the search with a file 
opened earlier; the file(s) following it in the list are then left out of the 
search process. Whenever a new resource file is opened, it's added to the end of 
the list; this overrides any previous calls to UseResFile, causing the entire 
list of open resource files to be searched. For example, assume there are four 
open resource files (RO through R3); the search order is R3, R2, R1, RO. If you 
call UseResFile(R2), the search order becomes R2, R1, RQ; R3 is no longer 
searched. If you then open a fifth resource file (R4), it's added to the end of 
the list and the search order becomes R4, R3, R2, R1, RO. 


This procedure is useful if you no longer want to override a system resource 
with one by the same name in your application's resource file. You can call 
UseResFile(@) to leave the application resource file out of the search, causing 
only the system resource file to be searched. 


Warning: Early versions of some desk accessories may, upon closing, always 
set the current resource file to the one opened just before the 
accessory, ignoring any additional resource files that may have 
been opened while the accessory was open. To be safe, whenever a 
desk accessory may have been in use, call UseResFile to ensure 
access to resource files opened while the accessory was open. 


Getting Resource Types 

FUNCTION CountTypes : INTEGER; 

CountTypes returns the number of resource types in all open resource files. 
FUNCTION CountiTypes : INTEGER; 


CountlTypes is the same as CountTypes except that it returns the number of 
resource types in the current resource file only. 


PROCEDURE GetIndType (VAR theType: ResType; index: INTEGER) ; 
Given an index ranging from 1 to CountTypes (above), GetIndType returns a 


resource type in theType. Called repeatedly over the entire range for the index, 
it returns all the resource types in all open resource files. If the given index 
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isn't in the range from 1 to CountTypes, GetIndType returns four NULL characters 
(ASCII code Q). 


PROCEDURE GetlIndType (VAR theType: ResType; index: INTEGER) ; 


Assembly-language note: The macro you invoke to call GetlIndType from assembly 
language is named GetllIxType. 


GetlIndType is the same as GetIndType except that it searches the current 
resource file only. Given an index ranging from 1 to CountlTypes (above), 
GetlIndType returns a resource type in theType. Called repeatedly over the 
entire range for the index, it returns all the resource types in the current 
resource file. If the given index isn't in the range from 1 to CountlTypes, 
GetlIndType returns four NULL characters (ASCII code 0). 


Getting and Disposing of Resources 
PROCEDURE SetResLoad (load: BOOLEAN); 


Normally, the routines that return handles to resources read the resource data 
into memory if it's not already in memory. SetResLoad(FALSE) affects all those 
routines so that they will not read the resource data into memory and will 
return an empty handle. Furthermore, resources whose resPreload attribute is set 
will not be read into memory when a resource file is opened. 


Warning: If you call SetResLoad(FALSE), be sure to restore the normal state 
as soon as possible, because other parts of the Toolbox that call 
the Resource Manager rely on it. 


Assembly-language note: The current SetResLoad state is stored in the global 
variable ResLoad. 


FUNCTION CountResources (theType: ResType) : INTEGER; 


CountResources returns the total number of resources of the given type in all 
open resource files. 


FUNCTION Count1Resources (theType: ResType) : INTEGER; 


CountiResources is the same as CountResources except that it returns the total 
number of resources of the given type in the current resource file only. 


FUNCTION GetIndResource (theType: ResType; index: INTEGER) : Handle; 


Given an index ranging from 1 to CountResources(theType), GetIndResource returns 
a handle to a resource of the given type (see CountResources, above). Called 
repeatedly over the entire range for the index, it returns handles to all 
resources of the given type in all open resource files. GetIndResource reads the 
resource data into memory if it's not already in memory, unless 

you've called SetResLoad(FALSE). 


Warning: The handle returned will be an empty handle if you've called 
SetResLoad(FALSE) (and the data isn't already in memory). The handle 
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will become empty if the resource data for a purgeable resource is 
read in but later purged. (You can test for an empty handle with, 
for example, myHndl* = NIL.) To read in the data and make the handle 
no longer be empty, you can call LoadResource. 


GetIndResource returns handles for all resources in the most recently opened 
resource file first, and then for those in the resource files opened before it, 
in the reverse of the order that they were opened. 


Note: The UseResFile procedure affects which file the Resource Manager 
searches first when looking for a particular resource but not when 
getting indexed resources with GetIndResource. 


If you want to find out how many resources of a given type are in a particular 
resource file, you can do so as follows: Call GetIndResource repeatedly with 
the index ranging from 1 to the number of resources of that type 
(CountResources(theType)). Pass each handle returned by GetIndResource to 
HomeResFile and count all occurrences where the reference number returned is 
that of the desired file. Be sure to start the index from 1, and to call 
SetResLoad(FALSE) so the resources won't be read in. 


If the given index is 0 or negative, GetIndResource returns NIL, but the 
ResError function will return the result code noErr. If the given index is 
larger than the value CountResources(theType), GetIndResource returns NIL and 
the ResError function will return the result code resNotFound. GetIndResource 
also returns NIL if the resource is to be read into memory but won't fit; in 
this case, ResError will return an appropriate Operating System result code. 


FUNCTION GetlIndResource (theType: ResType; index: INTEGER) : Handle; 


Assembly-language note: The macro you invoke to call GetlIndResource from 
assembly Language is named Get1IxResource 
GetlIndResource is the same as GetIndResource except 
that it searches the current resource file only. Given 
an index ranging from 1 to CountiResources(theType) , 
GetlIndResource returns a handle to a resource of the 
given type (see CountlResources, above). Called 
repeatedly over the entire range for the index, it 
returns handles to all resources of the given type in 
the current resource file. 


FUNCTION GetResource (theType: ResType; theID: INTEGER) : Handle; 


GetResource returns a handle to the resource having the given type and ID 
number, reading the resource data into memory if it's not already in memory and 
if you haven't called SetResLoad(FALSE) (see the warning above for 
GetIndResource). If the resource data is already in memory, GetResource just 
returns the handle to the resource. 


GetResource looks in the current resource file and all resource files opened 
before it, in the reverse of the order that they were opened; the system 
resource file is searched last. If it doesn't find the resource, GetResource 
returns NIL and the ResError function will return the result code resNotFound. 
GetResource also returns NIL if the resource is to be read into memory but 
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won't fit; in this case, ResError will return an appropriate Operating System 
result code. 


Note: If you call GetResource with a resource type that isn't in any open 
resource file, it returns NIL but the ResError function will return 
the result code noErr. 


FUNCTION GetlResource (theType: ResType; theID: INTEGER) : Handle; 


GetlResource is the same as GetResource except that it searches the current 
resource file only. 


FUNCTION RGetResource (theType: ResType; theID: INTEGER) : Handle; 


RGetResource is identical in function to GetResource except that it looks 
through the chain of open resource files for the specified resource, and if it 
doesn't find it there, it looks in the ROM resources. 


Note: With System file version 4.1 or later, RGetResource will also work on 
the Macintosh Plus. 


FUNCTION GetNamedResource (theType: ResType; name: Str255) : Handle; 


GetNamedResource is the same as GetResource (above) except that you pass a 
resource name instead of an ID number. 


FUNCTION GetlNamedResource (theType: ResType; name: Str255) : Handle; 


GetlNamedResource is the same as GetNamedResource except that it searches the 
current resource file only. 


PROCEDURE LoadResource (theResource: Handle); 


Given a handle to a resource (returned by GetIndResource, GetResource, or 
GetNamedResource), LoadResource reads that resource into memory. It does nothing 
if the resource is already in memory or if the given handle isn't a handle to a 
resource; in the latter case, the ResError function will return the result code 
resNotFound. Call this procedure if you want to access the data for a resource 
through its handle and either you've called SetResLoad(FALSE) or the resource is 
purgeable. 


If you've changed the resource data for a purgeable resource and the resource is 
purged before being written to the resource file, the changes will be lost; 
LoadResource will reread the original resource from the resource file. See the 
descriptions of ChangedResource and SetResPurge for information about how to 
ensure that changes made to purgeable resources will be written to the resource 
file. 


Assembly-language note: LoadResource preserves all registers. 
PROCEDURE ReleaseResource (theResource: Handle); 
Given a handle to a resource, ReleaseResource releases the memory occupied by 


the resource data, if any, and replaces the handle to that resource in the 
resource map with NIL (see Figure 9). The given handle will no longer be 
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recognized as a handle to a resource; if the Resource Manager is subsequently 
called to get the released resource, a new handle will be allocated. Use this 
procedure only after you're completely through with a resource. 


resource map 


resource data 


TYPE myHndl: Handle: 
myHndl := 
GetResource(type, ID} 


After : 
ReleaseResource(myHnd)) DetachResource(myHndl} 
resource map resource map 

NIL 


myHndl 


Figure 9—ReleaseResource and DetachResource 
Figure 9—ReleaseResource and DetachResource 


If the given handle isn't a handle to a resource, ReleaseResource will do 
nothing and the ResError function will return the result code resNotFound. 
ReleaseResource won't let you release a resource whose resChanged attribute has 
been set; however, ResError will still return noErr. 


PROCEDURE DetachResource (theResource: Handle); 


Given a handle to a resource, DetachResource replaces the handle to that 
resource in the resource map with NIL (see Figure 9 above). The given handle 
will no longer be recognized as a handle to a resource; if the Resource Manager 
is subsequently called to get the detached resource, a new handle will be 
allocated. 


DetachResource is useful if you want the resource data to be accessed only by 
yourself through the given handle and not by the Resource Manager. 
DetachResource is also useful in the unusual case that you don't want a resource 
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to be released when a resource file is closed. To copy a resource, you can call 
DetachResource followed by AddResource (with a new resource ID). 


If the given handle isn't a handle to a resource, DetachResource will do nothing 
and the ResError function will return the result code resNotFound. 
DetachResource won't let you detach a resource whose resChanged attribute has 
been set; however, ResError will still return noErr. 


Getting Resource Information 
FUNCTION UniqueID (theType: ResType) : INTEGER; 


UniqueID returns an ID number greater than 0 that isn't currently assigned to 
any resource of the given type in any open resource file. Using this number when 
you add a new resource to a resource file ensures that you won't duplicate a 
resource ID and override an existing resource. 


Warning: It's possible that UniqueID will return an ID in the range reserved 
for system resources (@ to 127). You should check that the ID 
returned is greater than 127; if it isn't, call UniqueID again. 


FUNCTION UniquelID (theType: ResType) : INTEGER; 


UniquelID is the same as UniqueID except that the ID number it returns is unique 
only with respect to resources in the current resource file. 


PROCEDURE GetResInfo (theResource: Handle; VAR theID: INTEGER; 
VAR theType: ResType; VAR name: Str255); 


Given a handle to a resource, GetResInfo returns the ID number, type, and name 
of the resource. If the given handle isn't a handle to a resource, GetResInfo 
will do nothing and the ResError function will return the result code 
resNotFound. 


FUNCTION GetResAttrs (theResource: Handle) : INTEGER; 


Given a handle to a resource, GetResAttrs returns the resource attributes for 
the resource. (Resource attributes are described above under "Resource 
References".) If the given handle isn't a handle to a resource, GetResAttrs will 
do nothing and the ResError function will return the result code resNotFound. 


FUNCTION SizeResource (the Resource: Handle) : LONGINT; 


Assembly-language note: The macro you invoke to call SizeResource from 
assembly Language is named SizeRsrc. 


Given a handle to a resource, SizeResource returns the size in bytes of the 
resource in the resource file. If the given handle isn't a handle to a resource, 
SizeResource will return —1 and the ResError function will return the result 
code resNotFound. It's a good idea to call SizeResource and ensure that 
sufficient space is available before reading a resource into memory. 


FUNCTION MaxSizeRsrc (theResource: Handle) : LONGINT; 


@ SpInside Macintosh * Version 1.0 * November 1989 * Apple Computer 
THE RESOURCE MANAGER ¢ 34 of 54 


MaxSizeRsrc is similar to SizeResource except that it does not cause the disk to 
be read; instead it determines the size (in bytes) of the resource from the 
offsets found in the resource map. 


Since MaxSizeRsrc does not read from the disk, it returns only the maximum size 
of the resource. In other words, you can count on the resource not being larger 
than the number of bytes reported by MaxSizeRsrc; it's possible, however, that 
the resource is actually smaller than the resource map indicates (because the 
file has not yet been compacted). If called after UpdateResFile, MaxSizeRsrc 
will return the correct size of the resource. 


Modifying Resources 


Except for UpdateResFile and WriteResource, all the routines described below 
change the resource map in memory and not the resource file itself. 


PROCEDURE SetResInfo (theResource: Handle; theID: INTEGER; name: Str255); 


Given a handle to a resource, SetResInfo changes the ID number and name of the 
resource to the given ID number and name. 


Assembly-language note: If you pass 0 for the name parameter, the name will 
not be changed. 


Warning: It's a dangerous practice to change the ID number and name of a 
system resource, because other applications may already access the 
resource and may no longer work properly. 


The change will be written to the resource file when the file is updated if you 
follow SetResInfo with a call to ChangedResource. 


Warning: Even if you don't call ChangedResource for this resource, the change 
may be written to the resource file when the file is updated. If 
you've ever called ChangedResource for any resource in the file, or 
if you've added or removed a resource, the Resource Manager will 
write out the entire resource map when it updates the file, so all 
changes made to resource information in the map will become permanent. 
If you want any of the changes to be temporary, you'll have to 
restore the original information before the file is updated. 


SetResInfo does nothing in the following cases: 


« The given handle isn't a handle to a resource. The ResError function will 
return the result code resNotFound. 
« The resource map becomes too large to fit in memory (which can happen if 
a name is passed) or the modified resource file can't be written out to 
the disk. ResError will return an appropriate Operating System result code. 
¢ The resProtected attribute for the resource is set. ResError will, 
however, return the result code noErr. 
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PROCEDURE SetResAttrs (theResource: Handle; attrs: INTEGER); 


Given a handle to a resource, SetResAttrs sets the resource attributes for the 
resource to attrs. (Resource attributes are described above under "Resource 
References".) The resProtected attribute takes effect immediately; the others 
take effect the next time the resource is read in. 


Warning: Do not use SetResAttrs to set the resChanged attribute; you must 
call ChangedResource instead. Be sure that the attrs parameter 
passed to SetResAttrs doesn't change the current setting of this 
attribute; to determine the current setting, first call GetResAttrs. 


The attributes set with SetResAttrs will be written to the resource file when 
the file is updated if you follow SetResAttrs with a call to ChangedResource. 
However, even if you don't call ChangedResource for this resource, the change 
may be written to the resource file when the file is updated. See the last 
warning for SetResInfo (above). 


eeeClick on the X-Ref button, and refer to Technical Note #78.+¢e¢« 


If the given handle isn't a handle to a resource, SetResAttrs will do nothing 
and the ResError function will return the result code resNotFound. 


PROCEDURE ChangedResource (theResource: Handle); 


Call ChangedResource after changing either the information about a resource in 
the resource map (as described above under SetResInfo and SetResAttrs) or the 
resource data for a resource, if you want the change to be permanent. Given a 
handle to a resource, ChangedResource sets the resChanged attribute for the 
resource. This attribute tells the Resource Manager to do both of the following: 


e write the resource data for the resource to the resource file when the file 
is updated or when WriteResource is called 
e write the entire resource map to the resource file when the file is updated 


Warning: If you change information in the resource map with SetResInfo or 
SetResAttrs and then call ChangedResource, remember that not only 
the resource map but also the resource data will be written out when 
the resource file is updated. 


To change the resource data for a purgeable resource and make the change 
permanent, you have to take special precautions to ensure that the resource 
won't be purged while you're changing it. You can make the resource temporarily 
unpurgeable and then write it out with WriteResource before making it purgeable 
again. You have to use the Memory Manager procedures HNoPurge and HPurge to make 
the resource unpurgeable and purgeable; SetResAttrs can't be used because it 
won't take effect immediately. For example: 


myHndl := GetResource(type, ID) ; {or LoadResource(myHndl) if } 
{ you've gotten it previously} 
HNoPurge(myHndlL) ; {make it unpurgeable} 
er {make the changes here} 
ChangedResource(myHnd1L) ; {mark it changed} 
WriteResource(myHndl) ; {write it out} 
HPurge(myHndl) {make it purgeable again} 
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Or, instead of calling WriteResource to write the data out immediately, you can 
call SetResPurge(TRUE) before making any changes to purgeable resource data. 


ChangedResource does nothing in the following cases: 


e The given handle isn't a handle to a resource. The ResError function will 
return the result code resNotFound. 

¢ The modified resource file can't be written out to the disk. ResError will 
return an appropriate Operating System result code. 

¢ The resProtected attribute for the modified resource is set. ResError will, 
however, return the result code noErr. 


eeeClick on the X-Ref button, and refer to Technical Note #188. ¢ee 


Warning: Be aware that if the modified file can't be written out to the disk, 
the resChanged attribute won't be set. This means that when 
WriteResource is called, it won't know that the resource file has 
been changed; it won't write out the modified file and no error will 
be returned. For this reason, always check to see that 
ChangedResource returns noErr. 


PROCEDURE AddResource (theData: Handle; theType: ResType; 
theID: INTEGER; name: Str255); 


Given a handle to data in memory (not a handle to an existing resource), 
AddResource adds to the current resource file a resource reference that points 
to the data. It sets the resChanged attribute for the resource, so the data will 
be written to the resource file when the file is updated or when WriteResource 
is called. If the given handle is empty, zero-length resource data will be 
written. 


Note: To make a copy of an existing resource, call DetachResource before 
calling AddResource. To add the same data to several different resource 
files, call the Operating System Utility function HandToHand to 
duplicate the handle for each resource reference. 


AddResource does nothing in the following cases: 


¢ The given handle is NIL or is already a handle to an existing resource 
. The ResError function will return the result code addResFailed. 

« The resource map becomes too large to fit in memory or the modified 
resource file can't be written out to the disk. ResError will return an 
appropriate Operating System result code. (The warning under 
ChangedResource above concerning the resChanged attribute also applies 
to AddResource. ) 


Warning: AddResource doesn't verify whether the resource ID you pass is 
already assigned to another resource of the same type; be sure to 
call UniqueID before adding a resource. 


PROCEDURE RmveResource (theResource: Handle); 
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Given a handle to a resource in the current resource file, RmveResource removes 
its resource reference. The resource data will be removed from the resource file 
when the file is updated. 


Note: RmveResource doesn't release the memory occupied by the resource data; 
to do that, call the Memory Manager procedure DisposHandle after calling 
RmveResource. 


If the resProtected attribute for the resource is set or if the given handle 
isn't a handle to a resource in the current resource file, RmveResource will do 
nothing and the ResError function will return the result code rmvResFailed. 


PROCEDURE UpdateResFile (refNum: INTEGER); 
Given the reference number of a resource file, UpdateResFile does the following: 


e Changes, adds, or removes resource data in the file as appropriate to 
match the map. Remember that changed resource data is written out only if 
you called ChangedResource (and the call was successful). UpdateResFile 
calls WriteResource to write out changed or added resources. 

¢ Compacts the resource file, closing up any empty space created when a 
resource was removed, made smaller, or made larger. (If the size of a 
changed resource is greater than its original size in the resource file, 
it's written at the end of the file rather than at its original location; 
the space occupied by the original is then compacted.) The actual size of 
the resource file will be adjusted when a resource is removed or made 
larger, but not when a resource is made smaller. 

¢ Writes out the resource map of the resource file, if you ever called 
ChangedResource for any resource in the file or if you added or removed 
a resource. All changes to resource information in the map will become 
permanent as a result of this, so if you want any such changes to be 
temporary, you must restore the original information before calling 
UpdateResFile. 


If there's no open resource file with the given reference number, UpdateResFile 
will do nothing and the ResError function will return the result code 
resFNotFound. A refNum of © represents the system resource file. 


The CloseResFile procedure calls UpdateResFile before it closes the resource 
file, so you only need to call UpdateResFile yourself if you want to update the 
file without closing it. 


PROCEDURE WriteResource (theResource: Handle); 


Given a handle to a resource, WriteResource checks the resChanged attribute for 
that resource and, if it's set (which it will be if you called ChangedResource 

or AddResource successfully), writes its resource data to the resource file and 
clears its resChanged attribute. 


Warning: Be aware that ChangedResource and AddResource determine whether the 
modified file can be written out to the disk; if it can't, the 
resChanged attribute won't be set and WriteResource will be unaware 
of the modifications. For this reason, always verify that 
ChangedResource and AddResource return noErr. 


@ SpInside Macintosh * Version 1.0 * November 1989 * Apple Computer 
THE RESOURCE MANAGER ¢ 38 of 54 


If the resource is purgeable and has been purged, zero-length resource data will 
be written. WriteResource does nothing if the resProtected attribute for the 
resource is set or if the resChanged attribute isn't set; in both cases, 
however, the ResError function will return the result code noErr. If the given 
handle isn't a handle to a resource, WriteResource will do nothing and the 
ResError function will return the result code resNotFound. 


Since the resource file is updated when the application terminates or when you 
call UpdateResFile (or CloseResFile, which calls UpdateResFile), you only need 
to call WriteResource if you want to write out just one or a few resources 
immediately. 


Warning: The maximum size for a resource to be written to a resource file is 
32K bytes. 


PROCEDURE SetResPurge (install: BOOLEAN); 


SetResPurge(TRUE) sets a "hook" in the Memory Manager such that before purging 
data specified by a handle, the Memory Manager will first pass the handle to the 
Resource Manager. The Resource Manager will determine whether the handle is that 
of a resource in the application heap and, if so, will call WriteResource to 
write the resource data for that resource to the resource file if its resChanged 
attribute is set (see ChangedResource and WriteResource). SetResPurge(FALSE) 
restores the normal state, clearing the hook so that the Memory Manager will 
once again purge without checking with the Resource Manager. 


SetResPurge(TRUE) is useful in applications that modify purgeable resources. You 
still have to make the resources temporarily unpurgeable while making the 
changes, as shown in the description of ChangedResource, but you can set the 
purge hook instead of writing the data out immediately with WriteResource. 
Notice that you won't know exactly when the resources are being written out; 
most applications will want more control than this. If you wish, you can set 
your own such hook; for details, refer to the section "Memory Manager Data 
Structures" in the Memory Manager chapter. 
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ADVANCED ROUTINES 


The routines described in this section allow advanced programmers to have even 
greater control over resource file operations. Just as individual resources have 
attributes, an entire resource file also has attributes, which these routines 
manipulate. Like the attributes of individual resources, resource file 
attributes are specified by bits in the low-order byte of a word. The Resource 
Manager provides the following masks for setting or testing these bits: 


CONST mapReadOnly 
mapCompact 
mapChanged 


128; {set if file is read-only} 
64; {set to compact file on update} 
32; {set to write map on update} 


When the mapReadOnly attribute is set, the Resource Manager will neither write 
anything to the resource file nor check whether the file can be written out to 
the disk when the resource map is modified. When this attribute is set, 
UpdateResFile and WriteResource will do nothing, but the ResError function will 
return the result code noErr. 


Warning: If you set mapReadOnly but then later clear it, the resource file 
will be written even if there's no room for it on the disk. This 
would destroy the file. 


The mapCompact attribute causes the resource file to be compacted when the file 
is updated. It's set by the Resource Manager when a resource is removed, or when 
a resource is made larger and thus has to be written at the end of the resource 
file. You may want to set mapCompact to force compaction when you've only made 
resources smaller. 


The mapChanged attribute causes the resource map to be written to the resource 
file when the file is updated. It's set by the Resource Manager when you call 
ChangedResource or when you add or remove a resource. You can set mapChanged if, 
for example, you've changed resource attributes only and don't want to call 
ChangedResource because you don't want the resource data to be written out. 


FUNCTION GetResFileAttrs (refNum: INTEGER) : INTEGER; 


Given the reference number of a resource file, GetResFileAttrs returns the 
resource file attributes for the file. If there's no resource file with the 
given reference number, GetResFileAttrs will do nothing and the ResError 
function will return the result code resFNotFound. A refNum of © represents the 
system resource file. 


PROCEDURE SetResFileAttrs (refNum: INTEGER; attrs: INTEGER); 


Given the reference number of a resource file, SetResFileAttrs sets the resource 
file attributes of the file to attrs. If there's no resource file with the given 
reference number, SetResFileAttrs will do nothing but the ResError function will 
return the result code noErr. A refNum of 0 represents the system resource file, 
but you shouldn't change its resource file attributes. 
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FUNCTION RsrcMapEntry (theResource: Handle) : LONGINT; 


RsrcMapEntry provides a way to access the resource references in the resource 
map. Given a handle to a resource, RsrcMapEntry returns the offset of the 
resource's reference from the beginning of the resource map. (For more 
information on resource references and the structure of a resource map, see the 
section "Format of a Resource File" in the Resource Manager chapter.) If it 
doesn't find the resource, RsrcMapEntry returns NIL and the ResError function 
will return the result code resNotFound. If you pass it a NIL handle, 
RsrcMapEntry will return garbage but ResError will return the result code noErr. 


Warning: Since routines are provided for opening, accessing, and changing 
resources, there's really no reason to access resources directly. 
To avoid damaging the resource file, you should be extremely careful 
if you use RsrcMapEntry. 


FUNCTION OpenRFPerm (fileName: Str255; vRefNum: INTEGER; 
permission: Byte) : INTEGER; 


OpenRFPerm is similar to OpenResFile except that it allows you to specify the 
read/write permission of the resource file the first time it is opened; 
OpenRFPerm also lets you specify in vRefNum the directory or volume on which the 
file is located (see the File Manager chapter for more details on directories). 
Permission can have any of the values that you would pass to the File Manager; 
these values are given in "Low-Level File Manager Routines" in the File Manager 
chapter. 


OpenRFPerm, like OpenResFile, will not open the specified file twice; it simply 
returns the reference number already assigned to the file. In other words, 
OpenRFPerm cannot be used to open a second access path to a resource file nor 
can it be used to change the permission of an already open file. Since 
OpenRFPerm gives no indication of whether the file was already open, there's no 
way to tell whether the file's open permission is what you specified or what was 
specified by an earlier call. 


eeeClick on the X-Ref button, and refer to Technical Note #185. eee 
Note: The shared read/write permission described in the File Manager chapter 


has no effect with OpenRFPerm since the Resource Manager is unable to 
deal with a portion of a resource file. 
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RESOURCES WITHIN RESOURCES 


Resources may point to other resources; this section discusses how this is 
normally done, for programmers who are interested in background information 
about resources or who are defining their own resource types. 


In a resource file, one resource points to another with the ID number of the 
other resource. For example, the resource data for a menu includes the ID number 
of the menu's definition procedure (a separate resource that determines how the 
menu looks and behaves). To work with the resource data in memory, however, it's 
faster and more convenient to have a handle to the other resource rather than 
its ID number. Since a handle occupies two words, the ID number in the resource 
file is followed by a word containing 0; these two words together serve as a 
placeholder for the handle. Once the other resource has been read into memory, 
these two words can be replaced by a handle to it. (See Figure 10.) 


Note: The practice of using the ID number followed by 0 as a placeholder is 
simply a convention. If you like, you can set up your own resources to 
have the ID number followed by a dummy word, or even a word of useful 
information, or you can put the ID in the second rather than the first 
word of the placeholder. 


In the case of menus, the Menu Manager function GetMenu calls the Resource 
Manager to read the menu and the menu definition procedure into memory, and then 
replaces the placeholder in the menu with the handle to the procedure. There may 
be other cases where you call the Resource Manager directly and store the handle 
in the placeholder yourself. It might be useful in these cases to call 
HomeResFile to learn which resource file the original resource is located in, 
and then, before getting the resource it points to, call UseResFile to set the 
current resource file to that file. This will ensure that the resource pointed 
to is read from that same file (rather than one that was opened after it). 


Warning: If you modify a resource that points to another resource and you 
make the change permanent by calling ChangedResource, be sure you 
reverse the process described here, restoring the other resource's 
ID number in the placeholder. 
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Figure 10-—How Resources Point to Resources 


Figure 10—How Resources Point to Resources 
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FORMAT OF A RESOURCE FILE 


eeeClick on the X-Ref button, and refer to Technical Notes #141 & #203.¢+¢« 


You need to know the exact format of a resource file, described below, only if 
you're writing a program that will create or modify resource files directly; you 
don't have to know it to be able to use the Resource Manager routines. 


Tesowrce header 
(16 bytes) 


reserved for system use 
(112 bytes} én6 bytes 


application data 
(125 bytes) 


resousoce data 
Tesouice map 


Figure 11-—Format of a Resource File 


Figure 11—Format of a Resource File 


As illustrated in Figure 11, every resource file begins with a resource header. 
The resource header gives the offsets to and lengths of the resource data and 
resource map parts of the file, as follows: 


Number of bytes Contents 

4 bytes Offset from beginning of resource file to resource data 
4 bytes Offset from beginning of resource file to resource map 
4 bytes Length of resource data 

4 bytes Length of resource map 


Note: All offsets and lengths in the resource file are given in bytes. 
This is what immediately follows the resource header: 
Number of bytes Contents 


112 bytes Reserved for system use 
128 bytes Reserved for application data 
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eeeClick on the X-Ref button, and refer to Technical Note #62.¢¢¢ 
The application data may be whatever you want. 


The resource data follows the space reserved for the application data. It 
consists of the following for each resource in the file: 


Number of bytes Contents 

For each resource: 

4 bytes Length of following resource data 
n bytes Resource data for this resource 


To learn exactly what the resource data is for a standard type of resource, see 
the chapter describing the part of the Toolbox that deals with that resource 


type. 


After the resource data, the resource map begins as follows: 


Number of bytes Contents 
16 bytes 0 (reserved for copy of resource header) 
4 bytes 0 (reserved for handle to next resource map to be searched) 
2 bytes 0 (reserved for file reference number) 
2 bytes Resource file attributes 
2 bytes Offset from beginning of resource map to 
type list (see below) 
2 bytes Offset from beginning of resource map to 


resource name list (see below) 


After reading the resource map into memory, the Resource Manager stores the 
indicated information in the reserved areas at the beginning of the map. 


The resource map continues with a type list, reference lists, and a resource 
name list. The type list contains the following: 


Number of bytes Contents 
2 bytes Number of resource types in the map minus 1 


For each type: 


4 bytes Resource type 
2 bytes Number of resources of this type in the map minus 1 
2 bytes Offset from beginning of type list to reference list 


for resources of this type 
This is followed by the reference list for each type of resource, which contains 
the resource references for all resources of that type. The reference lists are 
contiguous and in the same order as the types in the type list. The format of a 
reference list is as follows: 
Number of bytes Contents 


For each reference 
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of this type: 


2 bytes Resource ID 

2 bytes Offset from beginning of resource name list 
to length of resource name, or —1 if none 

1 byte Resource attributes 

3 bytes Offset from beginning of resouce data to 
length of data for this resource 

4 bytes 0 (reserved for handle to resource) 


The resource name list follows the reference list and has this format: 
Number of bytes Contents 
For each name: 


1 byte Length of following resource name 
n bytes Characters of resource name 


Figure 12 shows where the various offsets lead to in a resource file, in general 
and also specifically for a resource reference. 
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Figure 12—Resource Reference in a Resource File 
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SUMMARY OF THE RESOURCE MANAGER 


Constants 
CONST 


{ Masks for resource attributes } 


resSysHeap = 64; {set if read into system heap} 
resPurgeable = 32; {set if purgeable} 

resLocked = 16; {set if locked} 

resProtected = 8; {set if protected} 

resPreload = 4; {set if to be preloaded} 

resChanged =<2) {set if to be written to resource file} 


{ Resource Manager result codes } 


resNotFound = -192; {resource not found} 

resFNotFound = -193; {resource file not found} 

addResFailed = -194; {AddResource failed} 

rmvResFailed = -196; {RmveResource failed} 

resAttrErr = -—198; {attribute inconsistent with operation} 
mapReadErr = -199; {map inconsistent with operation} 


{ Masks for resource file attributes } 


mapReadOnly = 128; {set if file is read-only} 

mapCompact = 64; {set to compact file on update} 

mapChanged = 32; {set to write map on update} 
Data Types 


TYPE ResType = PACKED ARRAY[1..4] OF CHAR; 


Routines 
Initialization 


FUNCTION InitResources : INTEGER; 
PROCEDURE RsrcZoneInit; 


Opening and Closing Resource Files 
PROCEDURE CreateResFile (fileName: Str255); 


FUNCTION OpenResFile (fileName: Str255) : INTEGER; 
PROCEDURE CloseResFile (refNum: INTEGER); 
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Checking for Errors 
FUNCTION ResError : INTEGER; 
Setting the Current Resource File 


FUNCTION CurResFile : INTEGER; 


FUNCTION HomeResFile (theResource: Handle) INTEGER; 
PROCEDURE UseResFile (refNum: INTEGER); 
Getting Resource Types 
FUNCTION CountTypes INTEGER; 
FUNCTION CountiTypes INTEGER; 
PROCEDURE GetIndType (VAR theType: ResType; index: INTEGER); 
PROCEDURE GetlIndType (VAR theType: ResType; index: INTEGER); 
Getting and Disposing of Resources 
PROCEDURE SetResLoad (load: BOOLEAN) ; 
FUNCTION CountResources (theType: ResType) INTEGER; 
FUNCTION CountiResources (theType: ResType) INTEGER; 
FUNCTION GetIndResource (theType: ResType; index: INTEGER) Handle; 
FUNCTION GetlIndResource (theType: ResType; index: INTEGER) Handle; 
FUNCTION GetResource (theType: ResType; theID: INTEGER) Handle; 
FUNCTION Geti1Resource (theType: ResType; theID: INTEGER) : Handle; 
FUNCTION RGetResource (theType: ResType; theID: INTEGER) : Handle; 
FUNCTION GetNamedResource (theType: ResType; name: Str255) Handle; 
FUNCTION GetlNamedResource (theType: ResType; name: Str255) Handle; 
PROCEDURE LoadResource (theResource: Handle); 
PROCEDURE ReleaseResource (theResource: Handle); 
PROCEDURE DetachResource (theResource: Handle); 
Getting Resource Information 
FUNCTION UniqueID (theType: ResType) INTEGER; 
FUNCTION UniquelID (theType: ResType) INTEGER; 
PROCEDURE GetResInfo (theResource: Handle; VAR theID: INTEGER; 

VAR theType: ResType; VAR name: Str255); 
FUNCTION GetResAttrs (theResource: Handle) INTEGER; 
FUNCTION SizeResource (theResource: Handle) LONGINT; 
Modifying Resources 
FUNCTION MaxSizeRsrc (theResource: Handle) LONGINT; 
PROCEDURE SetResInfo (theResource: Handle; theID: INTEGER; 

name: Str255); 
PROCEDURE SetResAttrs (theResource: Handle; attrs: INTEGER); 
PROCEDURE ChangedResource (theResource: Handle); 
PROCEDURE AddResource (theData: Handle; theType: ResType; 
theID: INTEGER; name: Str255); 

PROCEDURE RmveResource (theResource: Handle); 
PROCEDURE UpdateResFile (refNum: INTEGER); 
PROCEDURE WriteResource (theResource: Handle); 
PROCEDURE SetResPurge (install: BOOLEAN); 
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THE RESOURCE 


Advanced Routines 


FUNCTION GetResFileAttrs 
PROCEDURE SetResFileAttrs 
FUNCTION RsrcMapEntry 
FUNCTION OpenRFPerm 


refNum: INTEGER) : INTEGER; 

refNum: INTEGER; attrs: INTEGER); 
theResource: Handle) : LONGINT; 
fileName: Str255; vRefNum: INTEGER; 
permission: Byte) : INTEGER; 


ee 


Assembly-Language Information 
Constants 


» Resource attributes 


resSysHeap .EQU 6 ;set if read into system heap 
resPurgeable .EQU 5 ;set if purgeable 

resLocked .EQU 4 ;set if locked 

resProtected .EQU 3 ;set if protected 

resPreload .EQU 2 ;set if to be preloaded 

resChanged .EQU 1 ;set if to be written to resource file 


; Resource Manager result codes 


resNotFound . EQU -192 sresource not found 

resFNotFound . EQU - 193 sresource file not found 

addResFailed . EQU -194 ;AddResource failed 

rmvResFailed . EQU -196 ;RmveResource failed 

resAttrErr .EQU —198 ;attribute inconsistent with operation 
mapReadErr .EQU —199 ;map inconsistent with operation 


» Resource file attributes 


mapReadOnly .EQU 7 ;set if file is read-only 
mapCompact . EQU 6 ;set to compact file on update 
mapChanged . EQU 5 ;set to write map on update 


; Values for setting RomMapInsert and TmpResLoad 


mapTrue .EQU $FFFF ;insert ROM map with TmpResLoad set to TRUE 
mapFalse .EQU $FFOO ;insert ROM map with TmpResLoad set to FALSE 


Special Macro Names 


Pascal name Macro name 
SizeResource _SizeRsrc 
GetlIndType _GetlIxType 


GetlIndResource _GetlIxResource 


Variables 
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TopMapHndl Handle to resource map of most recently opened resource file 


SysMapHndl Handle to map of system resource file 

SysMap Reference number of system resource file (word) 
CurMap Reference number of current resource file (word) 
ResLoad Current SetResLoad state (word) 

ResErr Current value of ResError (word) 

ResErrProc Address of resource error procedure 

SysResName Name of system resource file (length byte followed by 


up to 19 characters) 
RomMapInsert Flag for whether to insert map to the ROM resources (byte) 
TmpResLoad Temporary SetResLoad state for calls using RomMapInsert (byte) 
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Macintosh 128K Resource Manager 
Source Code Listing Modification History 
23 February 1984 


David T Craig -- 03 January 2004 


23 Feb 84 &2/BACK2: RMGR. TEXT Page 001 
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Resource Manager for the Macintosh Uscr Interface Standard 


Written by Bruce Horn 22 November 1982 


Copyright 1982 by Apple Computer, Inc. All Rights Reserved. 


This file contains the interface specification for the Resource Manager. 
It .Includes filcs which contain toolbox, graftype and sysmacs cquatcs 
and macro definitions, as well as the actual cade for the implementation 
of the Resource Manager. 


16-Dec-82 BLH Added Add/RmvcResource. Massive name changing. 

21-Jan-83 BLH Updated to new LK File system. 

11-Feb-83 BLH Returned error codes in InitResources, 
OpenResourec 

17-Feb-83 BLH Fixed bug in CheckLoad 

25-Apr-83 BLH Rom 3.0 averhaul: 


Fixed bug in UpdatcResFile, optimizing 
the writes and making it a little quicker 
to call updates. 


Changed openResFile to use the ecsource 
fork, and to handle more reasonably the 
alrcady-open, not-apen, and other error 
conditions. 


CloscResFilc now releases all resources 
in the map before closing, compacts the 
resources in the map, and writes out the 
possibly medificd map and header. 
(@@Notc--CloscResFile docs not compact 
yet. Due to a bug in GetHandleSize, 
this Feature has been disabled. ) 


The resource file starts at ZERO 
of 512. 


instcad 


Added memory full error handling in 
OpenResFile and CheckLaad. 


Added prcLoad capability to 
and OpenResourcc. 


initResources 


Added procedure WritcResource. 


Added ResAdded resource attribute. 


Added MAttr, map attributes word, in map. 


MapSize and DataSize are now LONGS. 


Resource manager routines now save 
ALL registers cxecpt AQ and 00. 


Added SctResPurge to handle the purge 
hook in the Memory Manager. 


Added CurResF ilc. 


12-May-83 AJH = fixed bug in InitResources -- shauldn’t preload when 
you can't read the map 


24-May-83 LH Fixed bug in NewMap--crashes if failed duc to unlink bug. 
25-May-83 BLH Changed interface to CmpString in GetNamedResourcc. 
3l-May-83 BLH Added CreatcResFile, Fixed AddResouree bugs. 

1-Jun-83 BLH Added DetachResource. 

6-Jun-83 BLH Fixed bug in GetNamedResauree (didn’t search all maps) 
8-Jun-83 BLH Fixed bug in CloseResaurce (!) 


10-Jun-83 BLH Moved campacting and mapwrite from CloscResFile to Updatc. 
Added routine to close maps in RsrcZoncinit. 
CloseResFile cleses all maps if you attcmpt to closc 
System. Rsre. UpdatcResFilc now compacts, since GetHandlcSize 
finally warks. 


13-Jun-83 BLH Made SctResAttr, SctResInfa NOT sect the mapChanged bit. 
you have to explicitly call ChangedResData to make sure 
the change is written out to the map. 


18-Jul-83 BLH Added MapCompact attribute bit to minimize resource File 
compacting. Added UniqueID ta rcturn a unique ID for a given 
type in the current map. Also, shrunk cade approximate ly 
60 bytes duc to suggestions from Donn Denman. 


8-Aug-83 BLH Removed BeginSubResourec, EndSubResaurce. Added HameResF ile. 

Added ResErrProc in globals. Made UniqucID return an 

ID which is unique in all open maps. Took out SctEOF 

from UpdatcResFilc, to allow pre-allacatian of the 

resource fork. Put in ResrvMcm ta reserve low locations for 
locked handles. Added filc-order preload and update to 
speed up resource 1/0. 


Split Resource Manager into four files: RMgr, RMgrAsml, 
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RMgrAsm2, and RMgrAsm3. Utilitics in RMgrAsm2. Added 
CheekGrew ta handic the DiskFull condition. CheckGrow 
called From ChangcdResource, AddResource, and AddReference. 
Also Added ReallocRes, AllocRes, called from (surprise! ) 
changedResource and AddResource to allocate space for 
cither a new resource or a resource which has changed 

size and necds to be reallocated at the end. 


16-Aug-83 BLH Bug fixes and spacc-savers. 


29-Aug-83 BLH Fixcd bug in SctResInfo, RmvcResource (protcet bit checked 
in RHndt instcad of RAttr) and made CheckGraw handle 
memoryFull condition as well as diskFull. 
AddResaurce /AddReference mow return ResErr=OiskFull or 
MemFull in the case that CheckGrow failed. 


1-Sep-83 BLH InitResources shouldn't clear ResErrProc. 
Fixed NOP (branch to next instr!), foldcd cmn code in 
name stuff. Fixed dangling ptr problem (!) caused by 
CheckGrew. Took out dangcrous LINK stuff in SctFilelO 
and just used a standard stackframce on first link in 
StdEntry. Made GetCurMap and CloscResFile handle the case 
of no maps open (sct curMap ta FFxx with ST). Fixed bug 
im LoadResource where crrors would not gct reported through 
the ResErrProc. AddResouree sets the Resource bit in the 
masterPtr, RmvcResouree and DetachResource clear it. 


2-Scp-83 BLH MAJOR CHANGE: threw away name ID stuff, made hard of fscts 
to the momes in the name block stared im the resource entry 
where the namc!0 was previously stored. This change 
fixed a timce-bomb bug which would trash the resource File 
after repeated SctResInfo calls. Also, data lengths in 
the resource file arc now LONG integers (4 bytes). Fixed 
CountTypes, GetIndType to rcturn truc counts and unique types 
for all open maps, ta be consistent with CountResources 
and GetIndResourcc. 


6-Scp-83 BLH Added MapReadOnly in MAttr to inhibit writing to the resource 
filc and diskFull checking. Added SctResFilecAttrs, 
GcetResFilcAttrs to allow toggling of this bit. 


89-Sep-83 BLH Fixed bug in CheckGrow which could trash the resource map 
if the handle passed to ChangedResource or AddResource 
was purged. 


93-Sep-83 BLH Fixed bug in CheckLoad--ResrvMem must preserve AO, so typed 
in .Word $A040 to replace ResrvMem. Fixed bug in RmvcNamc. 


10-Scp-83 BLH Fixed bug having to do with protected resources; cleaned 
up usage in UpdatcResFilc, ChangedResource, WritcResource 


SAIS ISIE SIS I ISSIRI SIS I SISIIIOIOIGIBICEIFISISICISIOIIIE SIRO FIC HII ii RR HF fof 


Version 7.0. Last modificd 10-Sep-83 by Srucc. 
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. Include  SysErr. Text ; System crrar canstants 

- Inc lude SysEqu. Text ; System cquates (memory layout... ) 
- Inc lude CrafE€qu. Text ;Basic graphics and sereen driver 
«Include Graf Types. Text ;Offsets into LisaGraf structures 
. Ine lude : QuickMacs. Text ylisaGraf traps 

. Inc lude SysMacs. Text ; System macros, linc1010 calls 

. Inc lude Too lMacs. Text ; ToolBox Referenecs 

- Include 3 Tao lEqu. Text ; Toolbox cquates 


-Proc 0 


~Ocf InitResources ;One-time call, initializes resource manager 
;and opens System.Resource ('refnum) 


-Ocf RsreZoncinit ;Zero all handics in the system map 
jwhich point to application heap zone 


.Def CreatcResF ile ;Given Filename, ercate a null res File 
.Ocf OpenResF ile ;Given filename, opens and returns refnum 
.Ocf UseResF ile ;Given refnum, sets current res file 


GetResFilcAttrs ;Given refnum, return resfile attributes. 
.Ocf SctResFilcAttrs ;Given refnum, set resfile attributes 


. Def UpdateResF ile ;Given rcefnum, update resource File 
CloscResF ile ;Given refnum, closes the resource 


SetResPurge ;Write resources when purging? 
SetResLoad ; Auto-Load an get? 


CountResources ;Given type, return number of resources 
GetIndResource ;Given index and type, returns handle 


CountTypes ; Returns number of types im current esre 
GetIndType ;Given index, rcturns type 


Un iqucID ;Given type, return a unique ID for that 


GetResource ;Given an ID and type, give handle back 
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Further Reference: 


File Manager 

Technical Note #1, Desk Accessories and System Resources 
Technical Note #6, Shortcut for Owned Resources 

Technical Note #23, Life With Font/DA Mover—Desk Accessories 
Technical Note #30, Font Height Tables 

Technical Note #32, Reserved Resource Types 

Technical Note #46, Separate Resource Files 

Technical Note #50, Calling SetResLoad 

Technical Note #62, Don't Use Resource Header Application Bytes 
Technical Note #74, Don't Use the Resource Fork for Data 
Technical Note #75, The Installer and Scripts 

Technical Note #78, Resource Manager Tips 

Technical Note #101, CreateResFile and the Poor Man's Search Path 
Technical Note #111, MoveHHi and SetResPurge 

Technical Note #116, AppleShare-able Apps & the Resource Manager 
Technical Note #141, Maximum Number of Resources in a File 
Technical Note #185, OpenRFPerm: What your mother never told you. 
Technical Note #188, ChangedResource: Too much of a good thing. 
Technical Note #203, Don't Abuse the Managers 

Technical Note #214, New Resource Manager Calls 

Technical Note #232, Strip With OpenResFile and OpenRFPerm 


END OF DOCUMENT 
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